Device Template File Properties
The IoT Sparkplug EIE sample device template file includes unique data group elements and attributes and may include a section specific to this EIE. This topic contains an example of an IoT Sparkplug device template file.
Device Template Elements and Attributes for the IoT Sparkplug EIE
Sparkplug defines a standard mechanism for formatting payload data, so very little customization is provided for in the device template file. The only customization allowed provides a mapping from payload text strings representing data units to CygNet units.
Payload Definition
The payloadDef section of an IoT Sparkplug EIE device template file contains information to allow users to interpret payload data for CygNet. This section is optional.
| Element | Description |
|---|---|
|
mapUnits |
Maps units in the payload to CygNet units. This section is needed only when the payload indicates data units that you want to import into CygNet. For example, CygNet represents kilograms as "kg", while a payload may use the text "KGRAM". This section of the device template file can be used to map the text string "KGRAM" from the payload to "kg" in CygNet. |
|
ex |
Each enumeration must begin with a lowercase e. It is then to be followed by a "units" text string as defined in the payload (e.g., units "KGRAM" in the payload is represented as eKGRAM.) Each enumeration element must be unique, but its value does not need to be unique. For example, using eKGRAM twice within a single enumeration list is illegal, but using the value "kg" for eKGRAM and eKILOGRAM is legal. Each enumeration must use a value attribute to define a constant value that corresponds to a valid CygNet unit. See PNT Engineering Units. |
Device Definition Attributes
The following table lists and describes IoT Sparkplug-specific device definition attributes.
| Attribute | Description |
|---|---|
|
class |
Set to "POC" if the payload represents a pump-off controller and includes dynagraph cards. Otherwise the attribute should be omitted. |
Data Group Attributes
The following table lists and describes IoT Sparkplug-specific data group attributes.
| Attribute | Description |
|---|---|
|
setUnreliableOnLostConnection |
If setUnreliableOnLostConnection is set to "true", all CygNet points will be set to unreliable upon receipt of a DEATH message for the topic associated with the data group. Otherwise the point status is unchanged. A DEATH message is issued when the MQTT server loses the connection to the remote device or node. |
|
uccRecv |
Set to "true" to allow a rebirth request to be issued via UIS command. |
|
canRecv |
Set to "true" to allow a rebirth request to be issued from CygNet Explorer. |
Data Group Elements
The following table lists and describes IoT Sparkplug-specific data group elements. These items are identified in the Sparkplug specification, but are optional and may not appear in all payload files.
| Data Group Element ID | Description |
|---|---|
|
_topicSeq |
The topic/payload sequence number. |
|
_topicUuid |
The topic/payload UUID. |
|
_topicTime |
The topic/payload data time. This value is used for point processing in the absence of a timestamp associated with each payload item. |
Data Group Element Attributes
The following table lists and describes IoT Sparkplug-specific attributes of data group elements.
| Attribute | Description |
|---|---|
|
itemId |
The required name of the item in the payload file. This is used to map an item in a payload file to a CygNet data group element. It is not used for data group elements _topicSeq, _topicUuid, or _topicTime, which are predefined in the Sparkplug specification. The itemId allows the following substitution strings :
|
|
type |
It is recommended that type variant ("vrnt") be used to preserve the data type provided in the payload. |
IoTSparkplug_Sample.dtf
The IoTSparkplug_Sample device template file includes data that defines what the Sparkplug payload looks like and where to find specific items in the payload. For more information about the Sparkplug specification, refer to the Sparkplug Specification document.
The following example displays the IoTSparkplug_Sample.dtf.
Example
 Click here to see an example of the template
<deviceDefinition deviceType="IoTSparkplugSample" mfg="CygNet" desc="IoT Sparkplug Sample" category="4098" model="Generic" eieType="IoTSparkplug" cygnetVersion="9.8.1000" customerVersion=""> <dataGroups udcCat="UDCALL" canSend="false" canRecv="false" uccSend="false" uccRecv="false" udcDefFac="true" baseOrd="0" devDG="false" maxCnt="1" forceSave="true" setUnreliableOnLostConnection="true">> <Topic1 niceName="Topic 1"> <dgElements secLev="4" type="vrnt"> <_topicSeq desc="Seq #"/> <_topicUuid desc="UUID"/> <_topicTime desc="Date/time (#)" hidden="true"/> <_topicTs desc="Date/time" ref="_topicTime" type="string" format="DateTime"/> <SignedI1 desc="Signed byte" itemId="sbyte1"/> <SignedI2 desc="Signed word" itemId="sword1"/> <SignedI4 desc="Signed double word (scaled)" itemId="sdword1" cvtF="Scale" sourceType="i4" type="r4" scaleFactor=".01" units="in"/> <SignedI8 desc="Signed quad word" itemId="sqword1"/> <Unsigned1 desc="Unsigned byte" itemId="ubyte1"/> <Unsigned2 desc="Unsigned short word" itemId="uword1"/> <Unsigned4 desc="Unsigned double word" itemId="udword1"/> <Unsigned8 desc="Unsigned quad word" itemId="uqword1"/> <Float desc="Float" itemId="float1"/> <Double desc="Double" itemId="double1"/> <Bool desc="Boolean" itemId="boolean1"/> <String desc="String" itemId="string1"/> </dgElements> </Topic1> </dataGroups> <defDataGroups/> <defUisCmds visible="true" canBeScheduled="true" clientCanInvoke="true" inheritsSecurity="false"/> </deviceDefinition> |
IoTSparkplug_POC.dtf
The IoTSparkplug_POC sample device template file includes the "Dynagraph Card" (DynaCard) data group. This device represents a pump-off controller, so the device class is identified as "POC" and the device template file includes a "Dynagraph Card" (DynaCard) data group. The "Dynagraph Card" data group includes data group elements only to support point processing. If point processing is not desired, they can be omitted.
The following example displays a section of the IoTSparkplug_POC.dtf. Note the attribute class="POC" in the deviceDefinition section.
For more information, see IoT Sparkplug EIE Dynagraph Card Data Group.
Example
|
Click here to see an example of the template
<deviceDefinition deviceType="IoTSparkplugPOC" mfg="CygNet" desc="IoT Sparkplug POC" category="4098" model="Generic" eieType="IoTSparkplug" class="POC" cygnetVersion="9.8.1000" customerVersion=""> <dataGroups udcCat="UDCALL" canSend="false" canRecv="false" uccSend="false" uccRecv="false" udcDefFac="true" baseOrd="0" devDG="false" maxCnt="1" forceSave="true" setUnreliableOnLostConnection="true">> <DynaCard niceName="Dynagraph Card" dgCat="internal" maxCnt="8"> <dgElements secLev="4" type="vrnt"> <SCnt desc="Surface point count"/> <SLMin desc="Surface min load"/> <SLMax desc="Surface max load"/> <DCnt desc="Downhole point count"/> <DLMin desc="Downhole min load"/> <DLMax desc="Downhole max load"/> <HrGgeOff desc="Hours since gauge off" units="hour"/> <StrkPeriod desc="Stroke period (secs/stroke)"/> <PumpSpeed desc="Pump speed (SPM)"/> <StrokeLen desc="Stroke length" units="in"/> </dgElements> </DynaCard> |
Sending Cards to ForeSite
For ForeSite to successfully collect cards from the IoT device, the IoTSparkplug_POC.dtf must include the CardCnt dgElement. While CardCnt is not necessary to collect cards in CygNet, ForeSite requires the element when pulling cards into its Card Library, and the IoT device template file is often used for ForeSite Edge. Card collection from the IoT device when CardCnt is not included in the device template file will fail.
Example
|
Click here to see an example of the template
<deviceDefinition deviceType="IoTSparkplugPOC" mfg="CygNet" desc="IoT Sparkplug Edge RPOC" category="4098" model="Generic" eieType="IoTSparkplug" class="POC" cygnetVersion="9.8.1000" customerVersion=""> <dataGroups udcCat="UDCALL" canSend="false" canRecv="false" uccSend="false" uccRecv="false" udcDefFac="true" baseOrd="0" devDG="false" maxCnt="1" forceSave="true"> <CfgDg niceName="Configurable Data Group" baseOrd="1" maxCnt="999"> <dgElements secLev="4"/> </CfgDg> <DynaCard niceName="Dynagraph Card" dgCat="internal" maxCnt="8"> <dgElements secLev="4"> <CardCnt desc="Card Num" readOnly="true" type="i4" isRef="1"> <ref prec="0" refOp="opAssign" value="1"/> </CardCnt> <CardNum desc="Card Num" readOnly="true" type="i4" isRef="1"> <ref prec="0" refOp="opAssign" value="1"/> </CardNum> </dgElements> </DynaCard> <OptCurStat niceName="Optimization Current Status"> <dgElements secLev="4" type="vrnt"> <_topicSeq desc="Seq #"/> <_topicUuid desc="UUID"/> <_topicTime desc="Date/time (#)" hidden="true"/> <_topicTs desc="Date/time" ref="_topicTime" type="string" format="DateTime"/> <P141 desc="Current SPM" udc="SPSTRN" itemId="SPSTRN"/> <P142 desc="Average SPM" udc="RRLSPMAVG" itemId="RRLSPMAVG"/> . . .
</dgElements> </OptCurStat> </dataGroups> <defDataGroups/> <defUisCmds visible="true" canBeScheduled="true" clientCanInvoke="true" inheritsSecurity="false"/> </deviceDefinition> |
